home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / man.3 / AddErrInfo.3 < prev    next >
Text File  |  1995-07-17  |  10KB  |  325 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/AddErrInfo.3,v 1.15 93/04/08 13:54:29 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .\" The definitions below are for supplemental macros used in Tcl/Tk
  24. .\" manual entries.
  25. .\"
  26. .\" .HS name section [date [version]]
  27. .\"    Replacement for .TH in other man pages.  See below for valid
  28. .\"    section names.
  29. .\"
  30. .\" .AP type name in/out [indent]
  31. .\"    Start paragraph describing an argument to a library procedure.
  32. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  33. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  34. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  35. .\"    needed;  use .AS below instead)
  36. .\"
  37. .\" .AS [type [name]]
  38. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  39. .\"    name are examples of largest possible arguments that will be passed
  40. .\"    to .AP later.  If args are omitted, default tab stops are used.
  41. .\"
  42. .\" .BS
  43. .\"    Start box enclosure.  From here until next .BE, everything will be
  44. .\"    enclosed in one large box.
  45. .\"
  46. .\" .BE
  47. .\"    End of box enclosure.
  48. .\"
  49. .\" .VS
  50. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  51. .\"    of man pages.
  52. .\"
  53. .\" .VE
  54. .\"    End of vertical sidebar.
  55. .\"
  56. .\" .DS
  57. .\"    Begin an indented unfilled display.
  58. .\"
  59. .\" .DE
  60. .\"    End of indented unfilled display.
  61. .\"
  62. '\"    # Heading for Tcl/Tk man pages
  63. .de HS
  64. .ds ^3 \\0
  65. .if !"\\$3"" .ds ^3 \\$3
  66. .if '\\$2'cmds'       .TH \\$1 1 \\*(^3 \\$4
  67. .if '\\$2'lib'        .TH \\$1 3 \\*(^3 \\$4
  68. .if '\\$2'tcl'        .TH \\$1 n \\*(^3 Tcl "Tcl Built-In Commands"
  69. .if '\\$2'tk'         .TH \\$1 n \\*(^3 Tk "Tk Commands"
  70. .if '\\$2'tclc'        .TH \\$1 3 \\*(^3 Tcl "Tcl Library Procedures"
  71. .if '\\$2'tkc'         .TH \\$1 3 \\*(^3 Tk "Tk Library Procedures"
  72. .if '\\$2'tclcmds'         .TH \\$1 1 \\*(^3 Tk "Tcl Applications"
  73. .if '\\$2'tkcmds'         .TH \\$1 1 \\*(^3 Tk "Tk Applications"
  74. .if t .wh -1.3i ^B
  75. .nr ^l \\n(.l
  76. .ad b
  77. ..
  78. '\"    # Start an argument description
  79. .de AP
  80. .ie !"\\$4"" .TP \\$4
  81. .el \{\
  82. .   ie !"\\$2"" .TP \\n()Cu
  83. .   el          .TP 15
  84. .\}
  85. .ie !"\\$3"" \{\
  86. .ta \\n()Au \\n()Bu
  87. \&\\$1    \\fI\\$2\\fP    (\\$3)
  88. .\".b
  89. .\}
  90. .el \{\
  91. .br
  92. .ie !"\\$2"" \{\
  93. \&\\$1    \\fI\\$2\\fP
  94. .\}
  95. .el \{\
  96. \&\\fI\\$1\\fP
  97. .\}
  98. .\}
  99. ..
  100. '\"    # define tabbing values for .AP
  101. .de AS
  102. .nr )A 10n
  103. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  104. .nr )B \\n()Au+15n
  105. .\"
  106. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  107. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  108. ..
  109. '\"    # BS - start boxed text
  110. '\"    # ^y = starting y location
  111. '\"    # ^b = 1
  112. .de BS
  113. .br
  114. .mk ^y
  115. .nr ^b 1u
  116. .if n .nf
  117. .if n .ti 0
  118. .if n \l'\\n(.lu\(ul'
  119. .if n .fi
  120. ..
  121. '\"    # BE - end boxed text (draw box now)
  122. .de BE
  123. .nf
  124. .ti 0
  125. .mk ^t
  126. .ie n \l'\\n(^lu\(ul'
  127. .el \{\
  128. .\"    Draw four-sided box normally, but don't draw top of
  129. .\"    box if the box started on an earlier page.
  130. .ie !\\n(^b-1 \{\
  131. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  132. .\}
  133. .el \}\
  134. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  135. .\}
  136. .\}
  137. .fi
  138. .br
  139. .nr ^b 0
  140. ..
  141. '\"    # VS - start vertical sidebar
  142. '\"    # ^Y = starting y location
  143. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  144. .de VS
  145. .mk ^Y
  146. .ie n 'mc \s12\(br\s0
  147. .el .nr ^v 1u
  148. ..
  149. '\"    # VE - end of vertical sidebar
  150. .de VE
  151. .ie n 'mc
  152. .el \{\
  153. .ev 2
  154. .nf
  155. .ti 0
  156. .mk ^t
  157. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  158. .sp -1
  159. .fi
  160. .ev
  161. .\}
  162. .nr ^v 0
  163. ..
  164. '\"    # Special macro to handle page bottom:  finish off current
  165. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  166. '\"    # page bottom macro.
  167. .de ^B
  168. .ev 2
  169. 'ti 0
  170. 'nf
  171. .mk ^t
  172. .if \\n(^b \{\
  173. .\"    Draw three-sided box if this is the box's first page,
  174. .\"    draw two sides but no top otherwise.
  175. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  176. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  177. .\}
  178. .if \\n(^v \{\
  179. .nr ^x \\n(^tu+1v-\\n(^Yu
  180. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  181. .\}
  182. .bp
  183. 'fi
  184. .ev
  185. .if \\n(^b \{\
  186. .mk ^y
  187. .nr ^b 2
  188. .\}
  189. .if \\n(^v \{\
  190. .mk ^Y
  191. .\}
  192. ..
  193. '\"    # DS - begin display
  194. .de DS
  195. .RS
  196. .nf
  197. .sp
  198. ..
  199. '\"    # DE - end display
  200. .de DE
  201. .fi
  202. .RE
  203. .sp .5
  204. ..
  205. .HS Tcl_AddErrorInfo tclc
  206. .BS
  207. .SH NAME
  208. Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_PosixError \- record information about errors
  209. .SH SYNOPSIS
  210. .nf
  211. \fB#include <tcl.h>\fR
  212. .sp
  213. \fBTcl_AddErrorInfo\fR(\fIinterp, message\fR)
  214. .sp
  215. \fBTcl_SetErrorCode\fR(\fIinterp, element, element, ...\fB (char *) NULL\fR)
  216. .sp
  217. char *
  218. \fBTcl_PosixError\fR(\fIinterp\fR)
  219. .SH ARGUMENTS
  220. .AS Tcl_Interp *message
  221. .AP Tcl_Interp *interp in
  222. Interpreter in which to record information.
  223. .AP char *message in
  224. Identifying string to record in \fBerrorInfo\fR variable.
  225. .AP char *element in
  226. String to record as one element of \fBerrorCode\fR variable.
  227. Last \fIelement\fR argument must be NULL.
  228. .BE
  229.  
  230. .SH DESCRIPTION
  231. .PP
  232. These procedures are used to manipulate two global variables
  233. that hold information about errors.
  234. The variable \fBerrorInfo\fR holds a stack trace of the
  235. operations that were in progress when an error occurred, and
  236. is intended to be human-readable.
  237. The variable \fBerrorCode\fR holds a list of items that
  238. are intended to be machine-readable.
  239. The first item in \fBerrorCode\fR identifies the class of
  240. .VS
  241. error that occurred (e.g. POSIX means an error occurred in
  242. .VE
  243. a POSIX system call) and additional elements in \fBerrorCode\fR
  244. hold additional pieces of information that depend on the class.
  245. See the Tcl overview manual entry for details on the various
  246. formats for \fBerrorCode\fR.
  247. .PP
  248. The \fBerrorInfo\fR variable is gradually built up as an
  249. error unwinds through the nested operations.
  250. Each time an error code is returned to \fBTcl_Eval\fR
  251. it calls the procedure \fBTcl_AddErrorInfo\fR to add
  252. additional text to \fBerrorInfo\fR describing the
  253. command that was being executed when the error occurred.
  254. By the time the error has been passed all the way back
  255. to the application, it will contain a complete trace
  256. of the activity in progress when the error occurred.
  257. .PP
  258. It is sometimes useful to add additional information to
  259. \fBerrorInfo\fR beyond what can be supplied automatically
  260. by \fBTcl_Eval\fR.
  261. \fBTcl_AddErrorInfo\fR may be used for this purpose:
  262. its \fImessage\fR argument contains an additional
  263. string to be appended to \fBerrorInfo\fR.
  264. For example, the \fBsource\fR command calls \fBTcl_AddErrorInfo\fR
  265. to record the name of the file being processed and the
  266. line number on which the error occurred;  for Tcl procedures, the
  267. procedure name and line number within the procedure are recorded,
  268. and so on.
  269. The best time to call \fBTcl_AddErrorInfo\fR is just after
  270. \fBTcl_Eval\fR has returned \fBTCL_ERROR\fR.
  271. In calling \fBTcl_AddErrorInfo\fR, you may find it useful to
  272. use the \fBerrorLine\fR field of the interpreter (see the
  273. \fBTcl_Interp\fR manual entry for details).
  274. .PP
  275. The procedure \fBTcl_SetErrorCode\fR is used to set the
  276. \fBerrorCode\fR variable.
  277. Its \fIelement\fR arguments give one or more strings to record
  278. in \fBerrorCode\fR:  each \fIelement\fR will become one item
  279. of a properly-formed Tcl list stored in \fBerrorCode\fR.
  280. \fBTcl_SetErrorCode\fR is typically invoked just before returning
  281. an error.
  282. If an error is returned without calling \fBTcl_SetErrorCode\fR
  283. then the Tcl interpreter automatically sets \fBerrorCode\fR
  284. to \fBNONE\fR.
  285. .PP
  286. \fBTcl_PosixError\fR
  287. .VS
  288. sets the \fBerrorCode\fR variable after an error in a POSIX kernel call.
  289. It reads the value of the \fBerrno\fR C variable and calls
  290. \fBTcl_SetErrorCode\fR to set \fBerrorCode\fR in the
  291. \fBPOSIX\fR format.
  292. In addition, \fBTcl_PosixError\fR returns a human-readable
  293. .VE
  294. diagnostic message for the error (this is the same value that
  295. will appear as the third element in \fBerrorCode\fR).
  296. It may be convenient to include this string as part of the
  297. error message returned to the application in \fIinterp->result\fR.
  298. .PP
  299. It is important to call the procedures described here rather than
  300. setting \fBerrorInfo\fR or \fBerrorCode\fR directly with
  301. \fBTcl_SetVar\fR.
  302. The reason for this is that the Tcl interpreter keeps information
  303. about whether these procedures have been called.
  304. For example, the first time \fBTcl_AppendResult\fR is called
  305. for an error, it clears the existing value of \fBerrorInfo\fR
  306. and adds the error message in \fIinterp->result\fR to the variable
  307. before appending \fImessage\fR;  in subsequent calls, it just
  308. appends the new \fImessage\fR.
  309. When \fBTcl_SetErrorCode\fR is called, it sets a flag indicating
  310. that \fBerrorCode\fR has been set;  this allows the Tcl interpreter
  311. to set \fBerrorCode\fR to \fBNONE\fB if it receives an error return
  312. when \fBTcl_SetErrorCode\fR hasn't been called.
  313. .PP
  314. If the procedure \fBTcl_ResetResult\fR is called, it clears all
  315. of the state associated with \fBerrorInfo\fR and \fBerrorCode\fR
  316. (but it doesn't actually modify the variables).
  317. If an error had occurred, this will clear the error state to
  318. make it appear as if no error had occurred after all.
  319.  
  320. .SH "SEE ALSO"
  321. Tcl_ResetResult, Tcl_Interp
  322.  
  323. .SH KEYWORDS
  324. error, stack, trace, variable
  325.